home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / nihcl-30.lha / nihcl-3.0 / doc / install.nihcl (.txt) next >
LaTeX Document  |  1990-05-25  |  15KB  |  339 lines
  1. \begindata{text,1080728}
  2. \textdsversion{12}
  3. \define{italic
  4. menu:[Font,Italic]
  5. attr:[FontFace Italic Int Set]}
  6. \define{bold
  7. menu:[Font,Bold]
  8. attr:[FontFace Bold Int Set]}
  9. \define{chapter
  10. menu:[Title,Chapter]
  11. attr:[Justification LeftJustified Point 0]
  12. attr:[FontFace Bold Int Set]
  13. attr:[FontSize PreviousFontSize Point 4]}
  14. \define{section
  15. menu:[Title,Section]
  16. attr:[Justification LeftJustified Point 0]
  17. attr:[FontFace Bold Int Set]
  18. attr:[FontSize PreviousFontSize Point 2]}
  19. \define{subsection
  20. menu:[Title,Subsection]
  21. attr:[Justification LeftJustified Point 0]
  22. attr:[FontFace Bold Int Set]}
  23. \define{paragraph
  24. menu:[Title,Paragraph]
  25. attr:[Justification LeftJustified Point 0]
  26. attr:[FontFace Italic Int Set]}
  27. \define{bigger
  28. menu:[Font,Bigger]
  29. attr:[FontSize PreviousFontSize Point 2]}
  30. \define{indent
  31. menu:[Region,Indent]
  32. attr:[LeftMargin LeftMargin Inch 32768]
  33. attr:[RightMargin RightMargin Inch 32768]}
  34. \define{typewriter
  35. menu:[Font,Typewriter]
  36. attr:[FontFace FixedFace Int Set]
  37. attr:[FontFamily AndyType Int 0]}
  38. \define{display
  39. menu:[Region,Display]
  40. attr:[LeftMargin LeftMargin Inch 32768]
  41. attr:[RightMargin RightMargin Inch 32768]
  42. attr:[Justification LeftJustified Point 0]}
  43. \define{example
  44. menu:[Region,Example]
  45. attr:[LeftMargin LeftMargin Inch 32768]
  46. attr:[Justification LeftJustified Point 0]
  47. attr:[FontFace FixedFace Int Set]
  48. attr:[FontFamily AndyType Int 0]}
  49. \define{description
  50. menu:[Region,Description]
  51. attr:[LeftMargin LeftMargin Cm 171084]
  52. attr:[Indent LeftMargin Cm -106350]}
  53. \define{quotation
  54. menu:[Region,Quotation]
  55. attr:[LeftMargin LeftMargin Inch 32768]
  56. attr:[RightMargin RightMargin Inch 32768]
  57. attr:[FontFace Italic Int Set]}
  58. \define{subscript
  59. menu:[Font,Subscript]
  60. attr:[Script PreviousScriptMovement Point 2]
  61. attr:[FontSize PreviousFontSize Point -2]}
  62. \define{superscript
  63. menu:[Font,Superscript]
  64. attr:[Script PreviousScriptMovement Point -6]
  65. attr:[FontSize PreviousFontSize Point -2]}
  66. \define{smaller
  67. menu:[Font,Smaller]
  68. attr:[FontSize PreviousFontSize Point -2]}
  69. \define{heading
  70. menu:[Title,Heading]
  71. attr:[LeftMargin LeftMargin Inch -13107]
  72. attr:[Justification LeftJustified Point 0]
  73. attr:[FontFace Bold Int Set]}
  74. \define{majorheading
  75. menu:[Title,MajorHeading]
  76. attr:[Justification Centered Point 0]
  77. attr:[FontSize PreviousFontSize Point 4]}
  78. \define{formatnote
  79. menu:[Region,FormatNote]
  80. attr:[Flags PassThru Int Set]}
  81. \define{subheading
  82. menu:[Title,Subheading]
  83. attr:[Justification LeftJustified Point 0]
  84. attr:[FontFace Bold Int Set]}
  85. \define{center
  86. menu:[Justify,Center]
  87. attr:[Justification Centered Point 0]}
  88. \define{flushleft
  89. menu:[Justify,FlushLeft]
  90. attr:[Justification LeftJustified Point 0]}
  91. \define{flushright
  92. menu:[Justify,FlushRight]
  93. attr:[Justification RightJustified Point 0]}
  94. \define{leftindent
  95. menu:[Region,LeftIndent]
  96. attr:[LeftMargin LeftMargin Inch 32768]}
  97. \define{code
  98. menu:[Region,Code]
  99. attr:[FontFace FixedFace Int Set]
  100. attr:[FontFamily AndyType Int 0]}
  101. \formatnote{.ds Cl Installation
  102. .so nihclmac.tr}
  103. \section{INTRODUCTION}
  104. \begindata{lookz, 1097376}
  105. hidden
  106. \enddata{lookz, 1097376}
  107. \view{lookzview,1097376,0,0,0}
  108. This is the Installation Guide for the NIH Class Library (previously known as 
  109. the "OOPS" Class Library) Revision 3.0.
  110. The NIH Class Library is intended to be portable to a UNIX system compatible 
  111. with either System V or 4.2/4.3BSD and which supports the AT&T C++ translator 
  112. Release 2.00, Release 2.1, or other compatible C++ compiler.  We have ported 
  113. and tested this library on the following systems:
  114. \indent{
  115. Sun-3 with SunOS 3.5
  116. Sun-3 with SunOS 4.0
  117. Sun-4 with SunOS 4.0
  118. Send comments to:
  119. \indent{Keith Gorlen
  120. Building 12A, Room 2033
  121. Computer Systems Laboratory
  122. Division of Computer Research and Technology
  123. National Institutes of Health
  124. Bethesda, MD 20892
  125. phone: (301) 496-1111
  126. Internet\indent{: kgorlen@alw.nih.gov}
  127. uucp: uunet!nih-csl!kgorlen
  128. \section{GUIDE TO THIS DISTRIBUTION KIT}
  129. The NIH Class Library distribution kit consists of a main directory and the 
  130. following subdirectories:
  131. \indent{\code{errfac     }Error Message Facility source files
  132. \code{lib        }Source files for the basic library classes
  133. \code{test       }Test suite for the basic library classes
  134. \code{vector     }Source files for the Vector classes
  135. \code{vectest    }Test suite for the Vector classes
  136. \code{ex         }Example programs for the book
  137. The main directory is refered to as \code{NIHCL} in the following discussion, 
  138. but may be placed anywhere.
  139. Most subdirectories have files named \code{MAKEFILE} and \code{Makefile}.  The 
  140. \code{MAKEFILE} is used by the installation procedure, and should work with 
  141. both the System V and BSD version of the \code{make} utility.  The fancier 
  142. \code{Makefile} is used for development, and may not work under BSD.
  143. \section{SUMMARY OF STEPS IN INSTALLING THE NIH CLASS LIBRARY}
  144. \description{1.    Update C++ system library and include files
  145. 2.    Edit \code{NIHCL/Makefile}
  146. 3.    Edit \code{NIHCL/lib/nihclconfig.h}
  147. 4.    Build and install error message facility*
  148. 5.    Build NIHCL basic classes, Vector classes, and test suite
  149. 6.    Test basic classes and Vector classes
  150. 7.    Build NIHCL basic classes, Vector classes, and test suite with multiple 
  151. inheritance support
  152. 8.    Test basic classes and Vector classes with multiple inheritance support
  153. 9.    Install class libraries*
  154. 10.    Build example programs
  155. 11.    Test example programs
  156. * root permission may be required
  157. \section{INSTALLING THE NIH CLASS LIBRARY
  158. }\subheading{
  159. }\subsection{1. Update C++ system library and include files}
  160. No updates to R2.00 of the AT&T C++ Translator are required.  However, if you 
  161. are using R2.1, be sure to make the changes documented in the section 
  162. \italic{COMPILING UNDER AT&T C++ TRANSLATOR RELEASE 2.1} in the \italic{NIH 
  163. Class Library Release Notes}.
  164. \subsection{2. Edit NIHCL/Makefile}
  165. Edit \code{NIHCL/Makefile} to change make variables as needed for your 
  166. environment.  Here are the settings shipped with the distribution kit:
  167. \example{\smaller{# C++ compiler
  168. CC = CC
  169. # C++ debug switch
  170. CCDEBUG =
  171. #CCDEBUG = -g
  172. # C++ flags
  173. # NOTE: Disable +p option when compiling with AT&T R2.1 
  174. #CCFLAGS = +p
  175. #CCFLAGS =
  176. # C++ include files
  177. I = /usr/include/CC
  178. # If using BSD
  179. SYS = BSD
  180. # If using System V
  181. #SYS = SYSV
  182. # Compile with nested types
  183. # (works with AT&T R2.1 and GNU C++)
  184. NESTED_TYPES =
  185. #NESTED_TYPES = -DNESTED_TYPES
  186. # Disable AT&T R2.0/R2.1 bug work-around code
  187. BUGDEFS =
  188. #BUGDEFS = -DBUG_bC2728 -DBUG_38 -DBUG_39 -DBUG_OPTYPECONST
  189. # Defining BUG_TOOBIG disables code that 
  190. # prevents C compiler "yacc stack overflows" error
  191. #BUGDEFS = -DBUG_bC2728 -DBUG_38 -DBUG_39 -DBUG_OPTYPECONST -DBUG_TOOBIG
  192. # Enable debug code
  193. DEBUGDEFS =
  194. #DEBUGDEFS = -DDEBUG_OBJIO -DDEBUG_PROCESS
  195. # Flags for ln
  196. #LNFLAGS =
  197. LNFLAGS = -s
  198. # If using "patch"
  199. MAIN = _main.c_p
  200. # If using "munch"
  201. #MAIN = _main.c_m
  202. # Target library for installation of Error Facility
  203. LIB_ID = libC
  204. # Target Directories for Installation
  205. # directory for libnihcl.a
  206. NIHCLLIBDIR = /usr/local/lib
  207. # directory for NIHCL include files
  208. NIHCLINCDIR = /usr/include/nihcl
  209. # directory where $\{LIB_ID\}.a resides
  210. CLIBDIR = /usr/local/lib/C++R2.0
  211. # directory for errgen utility
  212. ERRGENDIR = /usr/local/bin
  213. # directory for errgen table file
  214. ERRTABDIR = /usr/local/lib
  215. # directory for errlib.h and errors.h
  216. ERRINCDIR = $I}
  217. \subsection{3. Edit NIHCL/lib files}
  218. \paragraph{3.1 Edit \code{nihclconfig.h}}
  219. The NIH Class Library source is configured for your system by setting flags in 
  220. \code{NIHCL/lib/nihclconfig.h} which specify the machine model and operating 
  221. system (UNIX variant).
  222. To configure the NIH Class Library for one of the not yet implemented options, 
  223. at least all of the parameters appearing in \code{nihclconfig.h} will have to 
  224. be defined for that option.
  225. The NIH Class Library should configure itself automatically for the following 
  226. machines:
  227. \indent{sun/mc68000
  228. sun/sparc
  229. Classes \code{Process}, \code{HeapProc}, \code{StackProc}, \code{Scheduler}, 
  230. \code{Semaphore}, and \code{SharedQueue} have some machine-specific 
  231. dependencies and will not work unless the \code{SETJMP()/LONGJMP()} functions 
  232. are properly defined.  See the \italic{NIH Class Library Release Notes} for 
  233. directions on porting the \code{Process} classes.
  234. \paragraph{3.2 Edit \code{Object.h}}
  235. The file \code{Object.h} defines three versions of a preprocessor macro named 
  236. \code{STRINGIZE}, which forms some symbol names by concatenating the class 
  237. name argument with other strings.  Each version does this a different way. 
  238.  The version for use with ANSI C preprocessors, conditionalized on the symbol 
  239. \code{__STDC__}, uses \code{##} for concatenation.  If you are not using an 
  240. ANSI C preprocessor, defining the symbol \code{BS_NL} in \code{Object.h} 
  241. selects the version that uses the sequence \code{\\}<newline> as the 
  242. concatenation separator, which seems to work with most System V UNIX systems. 
  243.  If you do not define \code{BS_NL}, you get the version of DEFINE_CLASS that 
  244. uses an empty comment sequence (\code{/**/}), which works with most Berkeley 
  245. UNIX systems.
  246. \code{Object.h} should require no editing on most systems.
  247. \subsection{4. Install error message facility
  248. }(Skip this step for MASSCOMP/RTU)
  249. \example{su     (if installing in protected directory)
  250. make errorfacility}
  251. This builds an error message registery facility and error processing library 
  252. similar to \code{errcom} and the 3E library routines on the MASSCOMP.
  253. The \code{errgen} program reads a \code{.err} file to determine a facility 
  254. name, and then reads the file \code{$\{ERRTABDIR\}/errgen_tab} to lookup the 
  255. number assigned to that facility.  The facility number determines the 
  256. high-order bits of the error numbers which \code{errgen} assigns, assuring 
  257. that error numbers used by different libraries do not coincide.  Errgen 
  258. produces a \code{.h} file containing error symbols and their assigned numbers, 
  259. and a \code{.c} file containing a table of error messages and formatting 
  260. information.
  261. This step creates a module containing the error handling library routines 
  262. named \code{errors.o} and adds it to \code{$\{CLIBDIR\}/$\{LIB_ID\}.a}, and it 
  263. copies the files \code{errlib.h} and \code{errors.h} into the directory 
  264. \code{$\{ERRINCDIR\}.}
  265. The test program testerr on \code{NIHCL/errfac} verifies that the error 
  266. facilities have been built correctly.  It returns the first and last error 
  267. defined in the file \code{testerrs.err}.
  268. \subsection{5. Build the NIH Class Library, Vector classes, and test suite
  269. \example{make}
  270. \subsection{6. Test the NIH Class Library
  271. \example{make verify}
  272. This runs the test suite and compares the output of each test program with the 
  273. contents of a \code{.v} file containing the correct output.  If the program 
  274. runs correctly, you'll see the message "No differences encountered".  Some 
  275. tests such as \code{date}, \code{identdict}, \code{process}, \code{random}, 
  276. \code{stack}, and \code{tim} produce output to the terminal.  \code{date} 
  277. outputs yesterday's, today's, and tomorrow's date.  \code{identdict} dumps an 
  278. identity dictionary.  \code{random} prints out a list of random numbers. 
  279.  \code{stack} prints out a \code{CLTNEMPTY} error message to test error 
  280. reporting, and \code{tim} prints out the current date and time.
  281. The \code{error} test program frequently fails to compare because its output 
  282. depends upon memory addresses that change from implementation to 
  283. implementation.  \code{error} should differ only in the object address printed 
  284. in the \code{CLTNEMPTY} error message.
  285. The output of \code{fdset} depends upon the maximum number of allowable file 
  286. descriptors on your system.  The test output was generated under SunOS 4.0, 
  287. which has a limit of 64 file descriptors.
  288. Several tests that print floating point numbers may fail to compare due to 
  289. formatting differences.
  290. The byte size of the object printed by ex8-1 may vary for different systems. 
  291.  The test output was produced by a Sun-3.
  292. \subsection{7. Build the NIH Class Library, Vector classes, and test suite 
  293. with multiple inheritance support
  294. \example{make cleantest
  295. make mi
  296. \subsection{8. Test the NIH Class Library, Vector classes, and test suite with 
  297. multiple inheritance support
  298. \example{make verify
  299. This runs the same tests as in Step 6, with similar results.
  300. \subsection{9. Install the NIH Class Libraries
  301. \example{su     (if installing in protected directory)
  302. make install}
  303. The NIH Class Library archives \code{libnihcl.a}, \code{libnihclmi.a}, 
  304. \code{libnihclvec.a}, and \code{libnihclvecmi.a} are copied to 
  305. \code{$\{NIHCLLIBDIR\}} and \code{ranlib} is executed on the libraries.  All 
  306. header files for basic classes are copied to directory 
  307. \code{$\{NIHCLINCDIR\}}.
  308. \subsection{10. Build example programs
  309. \example{make examples}
  310. \subsection{11. Test example programs}
  311. \example{make exverify}
  312. \section{TROUBLE SHOOTING}
  313. \subsection{YACC stack overflows}
  314. Some test programs may fail to compile because they are too complicated for 
  315. your C compiler and get a "yacc stack overflow".  Either increase the table 
  316. space in your C compiler or simplify the program by breaking it up into 
  317. separate functions.  The inline copy constructors that Release 2.0 
  318. automatically generates are frequently the source of this error.  Explicitly 
  319. defining non-inline copy constructors solves the problem.  See the 
  320. \italic{Release Notes} for further details.
  321. \subsection{Problems with class Exception}
  322. Test programs error and except test class \code{Exception}, the the NIH Class 
  323. Library exception handler. If these programs fail to perform correctly 
  324. suspicion can be directed to the performance of system functions 
  325. \code{setjmp()} and \code{longjmp()}.
  326. \subsection{Problems with Process classes}
  327. Progams \code{process} and \code{stackproc} test the NIH Class Library 
  328. co-routine mechanism (classes \code{Process}, \code{HeapProc}, 
  329. \code{StackProc}, and \code{Scheduler}), the object queue (class 
  330. \code{SharedQueue}) and semaphore (class \code{Semaphore}).  These are 
  331. machine-dependent and rely on the presence of \code{alloca()}, which all 
  332. systems do not provide, and on \code{setjmp()}/\code{longjmp()} being 
  333. implemented by saving/restoring all machine registers, which is not always the 
  334. case for all systems either.  If the \code{process} or \code{stackproc} tests 
  335. fail to compile, link, or run, check your system's implementations of 
  336. \code{alloca()} \code{setjmp()}, and \code{longjmp()} -- you may need to 
  337. implement your own versions.
  338. \enddata{text,1080728}
  339.